Video Popularity Endpoint
Gracenote Video Popularity assigns a numeric score to TV series and movies that represents the majority of the population's level of recognition of a video program. Video Popularity data assigns a numeric 0 to 1 score to TV series and movies representing a general audience’s level of recognition of a video program. The score is based on a proprietary algorithm applied across a combination of Gracenote and Nielsen data sources to ensure a high-quality and consistent metadata product. The scores are optimized for program search, discovery, and editorial curation use cases.
API and Example Responses
API:
http://on-api.gracenote.com/v3/VideoPopularity
?updateId=[updateId value] &limit=[limit value] &api_key=[your-api-key]
Request Parameters
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Response Body
The table below shows parameters that may be included in Video Popularity response.
| Attribute | Description |
|---|---|
| tmsId | The TMSId of a program |
| score | Numeric Video Popularity score value. |
| score_date | Date of the score. |
Example Requests
http://on-api.gracenote.com/v3/VideoPopularity?limit=1&api_key=<your-api-key>&tmsId=SH014483860000
Example Responses
See Video Popularity XML examples
Video Popularity Program Types and Coverage
Popularity scores are calculated at the Root Id level for a program. All programs that are associated with the same Root Id will have the same popularity score.
Gracenote US Video Popularity covers the following programs:
- Programs that have aired in the United States
- Released TV series at the series level
- Released Movies
Gracenote US Video Popularity does not cover the following programs:
- Sports programming (e.g. specific sports games)
- One-time specials (e.g. the Oscars)
- Local news programming
- Episode-level popularity
Getting Seed Data and Updates
To download the entire endpoint, and to update it on a daily basis, follow the steps described here: API Data Delivery. Video Popularity scores for all programs are updated daily. You should check for updates regularly to ensure you are using the latest scores.
About IDs in Video Popularity
You should use a program's TMSId to look up its Video Popularity score. This returns the Video Popularity data and some other IDs as described below:
| ID Type | Description |
|---|---|
| Object ID | Video Popularity Object ID is an alpha-numeric ID that starts with “GN”. Each Object ID is a unique identifier for the combination of Root ID + country + date for a program. These IDs are transient and change every day.. The “object” associated with the Object ID includes all of the relevant Video Popularity score information for the given program. Object IDs are not meant to be used for program lookups in the API. |
| Root ID | The program Root ID is the main ID associated with a program’s Video Popularity score for a specific country. For example, the Video Popularity score in the US for the movie Titanic is associated with the Root ID for Titanic with US as the country of relevance. All relevant TMSIds under the given Root ID will have the same Video Popularity score for that country. |
| TMSIds | TMSIds are 14-character alpha-numeric IDs that start with only “SH” or “MV”. The TMSIds returned for Video Popularity are likely the most relevant for a specific country, but they are not necessarily a complete list. All relevant TMSIds for a given program Root ID will have the same Video Popularity score. |
Video Popularity Data Structure and Relationships
Popularity scores are calculated for programs at the rootId level - all programs that are associated with the same rootId will have the same popularity score. Video Popularity scores for all programs are updated daily. Check for updates regularly to ensure you are using the latest scores.
- Numeric score on a scale of 0-1 with 5 decimals is provided for each program
- Scoring algorithm weights multiple signals and factors including recency of release/airing
Schema
Review the following XML schema definition (xsd) to learn about the data structure, fields, and types for this endpoint.
To explore the relationships among all endpoints, see the interactive schema documentation.
XML Schema URL
http://files.api.gracenote.com/xsd/on_update_videoPopularities_3.22.xsd
The XPATH in the tables below is relative to on/videoPopularityScores/videoPopularityScore
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| @id | Popularity record identifier | GNLZZJ4023NN4K5 |
| @rootId | The rootId of the program | 22676161 |
| @country | Country associated with popularity record | USA |
| score | Video Popularity score value 0-1 | 0.62642 |
| scoreDate | Date of the score | 2024-05-20T00:00:00Z |
| programs/program/tmsId/ | The TMSId(s) of the program | MV020141020000 |
Entity Relationship Diagram
The following ERD illustrates the ID relationships from a Video Popularity record
